home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Essential Home & Business Collection
/
The Essential Home & Business Collection.iso
/
26
/
3
/
4
/
SPOOLK.ZIP
/
SPOOLKIT.DOC
< prev
next >
Wrap
Text File
|
1990-11-23
|
12KB
|
267 lines
┌──────────────────────────┐
┌┼──────────────────────────┼┐
││ SPOOLKIT.PBU ││
││ 23 Nov, 1990 ││
││ ││
││ Nathan C. Durland III ││
││ ││
└┼──────────────────────────┼┘
└──────────────────────────┘
BACKGROUND:
Ever since version 2, PC-DOS and MS-DOS have contained an external
program called PRINT. When first invoked, the PRINT program would
establish which port the printer was attached to, and then would leave
a piece of itself behind. I'll call the small portion "the resident".
The resident would then busy itself with stealing little pieces of
processor time, when nothing else was going on, and send the contents
of what ever file you wished to the printer. Now you could be twice
as productive, since you could work and print at the same time.
I have written several programs for other people that generated a lot
of printed output. I hated working hard to make the program run fast
and efficiently, only to wait for the printer. I had though about
creating print files, then using a command similar to the BASIC
"SHELL" statement to print the files. But this is inelegant, and it
didn't give me the control I needed over what was spooled, what
wasn't, what was done so I could overwrite the file, etc.
Finally, starting with version 3.x of DOS, the interface to the
resident was published. So, yours truly went to work and created some
BASIC subroutines that provide an interface to the PRINT resident.
The biggest advantage these routines offer is that they relieve the
programmer (you) of the burden of trapping printer errors (off-line,
out of paper, no power, what ever). The resident takes care of all
that. If all your print output is directed to files that are to be
spooled, you can then LINK your PowerBasic programs without the
printer library, and get smaller .EXE files.
REQUIREMENTS:
These routines require that you have PowerBasic 2.10, with the
PowerPack. If someone asks, I can modify them to work with PB 2.00.
Although the interface to the PRINT resident wasn't published until
version 3.x, a couple of DOS gurus I've talked to don't see why there
should be any problems using these routines with version 2.1. I can't
say, since I don't have access to a machine that is running anything
less than V3.2.
COMMENTS:
The comment header from each routine is included below, and each
routine is pretty self-explanatory. However, a couple of cautions are
in order:
1. Before you use any of these routines, make sure you have the PRINT
resident portion loaded. It is a bad practice to use the SHELL
statement from a basic program to load the resident. Why? Because
PRINT is a terminate-and-stay-resident (TSR) program. TSRs, by their
nature, will "lock" any program that is loaded before them into
memory. So, when your BASIC program ends, whatever memory it uses
will be unavailable to the next program you run.
2. If you call the ListSpooledFiles routine, make sure that f$() (or
what ever you choose to call the array for the returned file names)
is DIM'd large enough to hold all the entries. The PRINT command uses
the /Q:xx switch to determine the maximum number of queue entries.
This number can't be larger than 32, and is 10 by default. The SUB
assumes that the first element is number 1.
3. The SpoolInstalled% function will return a boolean (True/False)
value, based on whether the PRINT resident is detected. All the
other SUBs in SPOOLKIT return a status code. If the SUB executed
OK, then the status code will be 0. Otherwise, it will be set to
the error code that was retured by the interrupt call. No other
error checking is done by the subs. These are the possible error
codes:
0 = Call executed OK. No errors
1 = Function invalid. Most likely when a routine is called and
resident is not installed
2 = File not found
3 = Path not found
4 = Too many open files (increase the FILES= in CONFIG.SYS)
5 = Access denied. You can't read the file, or the queue is on hold.
8 = The print queue is full.
9 = Spooler busy. Wait, then try again.
12 = Name to long. File specifications must 64 bytes or less.
15 = Drive invalid.
I also used the following return codes in the SubmitSpoolFile routine
*16 = Spooler (resident) not installed
17 = Called with blank file specification
18 = No file met specification
* SubmitSpoolFile is the only one of these routines that will check for the
presence of the resident. This is to save time, since the routine may have
to process a long list of files before it actually tries to communicate
with the resident.
4. And finally, if you are writing a program using these routines, it
will not run correctly within the PowerBasic IDE. I have gotten in
touch with the folks at Spectra Publishing via CompuServe, and they are
looking into it. You can compile to an .EXE file and run it with out
any problems. SPKDEMO.EXE and .BAS are included so you can get a look
at the routines in action.
I hope you find these routines useful. The .ZIP file you extracted
this documentation from has a short demo of the functions of the
SPOOLKIT routines. The zip file should contain these files:
SPOOLKIT.DOC - What you're reading now
SPOOLKIT.PBU - PowerBasic unit file
SPOOLKIT.INC - Include file that contains required DECLAREs
SPKDEMO.BAS
SPKDEMO.EXE - Demo program
Source code is available upon request. Use of this software is free
for both personal and commercial use, and the software is supplied
without warranty, implied or otherwise. However, the author is not
adverse to accepting a small ($5.00) donation if you would like to send
one (This would encourage him to write more routines, or improve on
some of these!). Send any donations to:
Nathan C. Durland III
400 Margaret St, Apt #7
Plattsburgh, NY 12901
I can also be reached at CompuServ, user ID 76467,3355 or on PC-LINK,
screen name ShadowFax1.
Major routines in the SPOOLKIT are:
FUNCTION SpoolInstalled% LOCAL PUBLIC
' ------------------------------------------------------------------
' Detects if resident portion of DOS PRINT is installed
' No mechanism is provided here to detect that PRINT is not loaded
' but can be. This would encourage loading of PRINT.COM from a
' SHELL statement, which would lock all the memory used by the
' calling program.
'
' This function differs from the rest of the Spoolkit routines in
' that it returns a TRUE/FALSE value instead of the error code.
' ------------------------------------------------------------------
SUB SubmitSpoolFile(f$,FCount%,Stat%) LOCAL PUBLIC
' ------------------------------------------------------------------
' This routine will dispatch file(s) to the DOS PRINT spooler.
' Notice that this is the only SUB that checks for the presence of
' the PRINT resident. It does this to save time, since there is some
' work to be done before any spooling actually takes place. Wild
' card file specifications are not allowed by the interrupt call, but
' are acceptable to this routine. This sub will take a wild card spec
' and dispatch all matching files one at a time to the PRINT resident.
' Dispatching stops, however, if an error occurs while submitting a file.
'
' CALLING PARAMETERS:
'
' INPUT:
' f$ = File Specification to be submitted (wildcards OK)
' Stat% = Not Used
' FCount% = Not Used
'
' OUTPUT:
' f$ = Not Used
' Stat% = Error code from call. 0 Means everything is OK
' FCount% = Number of successfully files spooled. This is valid
' even if the routine takes an error.
'
' ------------------------------------------------------------------
'
SUB RemoveFromSpool(f$,Stat%) LOCAL PUBLIC
' ---------------------------------------------------------------------------
' Removes file(s) from the spool queue. Pass the full path and file name
' of the entry to be removed. Wildcards are allowed for this function.
' However, a drive and directory are required. If a drive/dir is not
' part of f$, the current default will be added. So, if your current
' directory is C:\PB\DOC, and you call RemoveFromSpool with f$ = XYZ.DOC,
' the file "C:\PB\DOC\XYZ.DOC" can be remove from the queue, but
' C:\MYDOC\XYZ.DOC will not be removed.
'
' Intresting technical note: Any wildard file specifications are
' converted to ????????.??? format (F*.BAT becomes F???????.???). This is
' because the interrupt will occasionaly return corrupt information if a
' '*' is in the file name; even though the DOS technical reference says it
' is legal. The ????????.??? format has worked flawlessly for me.
'
' PB Calling sequence:
' Passed IN: f$ = Name of file(s) to cancel
' Passed OUT: Stat% = Status code from call. 0 is OK
' ---------------------------------------------------------------------------
SUB CancelAllSpool(Stat%) LOCAL PUBLIC
' ------------------------------------------------------------------
' Removes all entries from the DOS PRINT spool queue. Use with
' appropriate caution
'
' PB Calling sequence:
' Passed IN: NONE
' Passed OUT: Stat% = Status code from call. 0 is OK
' ------------------------------------------------------------------
SUB HoldSpool(QueuedFiles$,Stat%) LOCAL PUBLIC
' ------------------------------------------------------------------
' Puts a hold on the DOS PRINT spool queue, and returns the list
' of files currently in the queue in a single string variable.
' Each file name in the variable is separated by an ASCII zero
' (CHR$(0)). The original list fof files returned by the DOS
' service is a structure of 64-byte entries. The file name in
' each entry is terminated with a single ASCII 0, and the rest of
' the structure contains leftover junk. HoldSpool strips out the
' unneeded bytes.
'
' PB Calling sequence:
' Passed IN: NONE
' Passed OUT: Stat% = Status code from call. 0 is OK
' QueuedFiles$ = string containing names of files
' in print queue, separated by
' CHR$(0)
'
' ---------------------------------------------------------------------
SUB StartSpool(Stat%) LOCAL PUBLIC
' ------------------------------------------------------------------
' Removes a hold on the DOS PRINT spool queue.
'
' PB Calling sequence:
' Passed IN: NONE
' Passed OUT: Stat% = Status code from call. 0 is OK
' ------------------------------------------------------------------
SUB ListSpooledFiles(f$(),FCount%,Stat%) LOCAL PUBLIC
' ---------------------------------------------------------------------------
' This routine will determine what files are queued to print, and will
' return their names in an array.
'
' A safe number to dimension f$() to is 32, this is the maximum number of
' files that can ever be queued to PRINT, at least in DOS versions 3 and 4
'
' PB Calling Sequence:
' Passed in: Nothing. f$() must be DIM'd, preferably to 32.
' No bounds checking is done by this SUB
' Passed out: f$() contains the names of the files queued.
'
' FCount% is the number of files. A partial list may
' have been created if there was an error
'
' Stat% is the Status. 0 means all is OK
' ---------------------------------------------------------------------------